home *** CD-ROM | disk | FTP | other *** search
/ Amiga Tools 5 / Amiga Tools 5.iso / libs / xprz35r.lha / docs / xprzedzap.doc < prev    next >
Text File  |  1994-11-26  |  9KB  |  208 lines
  1.     XRPzedzap.doc by Robert Williamson
  2.  
  3.    XPRzedzap.library is an enhanced version of xprzmodem.library for use in
  4. FTN   sessions.    The  xprzedzap.library  uses  the  3.1  version  of  the
  5. xprzmodem.library   as   its   base   and   uses   the   0.85   version  of
  6. xprzedzap.library  by  Yves  Konigshofer  for FTN-related extensions.  This
  7. version  was  audited  by  Yves and released with his approval of myself as
  8. KOTS for zedzap.
  9.  
  10.       Since  the  version  0.55  sources  were written for lattice C, I had
  11. decided  to  forget  about them AND the .85 and .90 sources and build a new
  12. one  from xprzmodem v3.1 source.  This source is compilable with SASc v6.51
  13. and  uses  the  libent  and  libinit  modules instead of the old latticelib
  14. assembly stubs.
  15.  
  16.   The  new  version has virtually all the useful xprzedzap v1.0 options and
  17. features  DirectZap  as  well  and ZedZap, ZedZip, SZmodem and Zmodem.  The
  18. protocol currently active is displayed in the xpr status window.
  19.  
  20. Mailers and XPR Protocols 
  21.  
  22.     Many  Mailers  make  use  of  XPR  protocols  to  provide file transfer
  23. capabilities  and  to  gain the advantage of easy addition of new protocols
  24. when they become available.  Those known to use XPP protocols include:
  25.  
  26.     POP, JAZ, RAP, UMBRELLA, GAZEBO, PORTICUS, ROOF, NORM and JAMMAIL.
  27.  
  28.    Since  Mailers  perform  a  fast  turaround  from  send  to  receive and
  29. vise-versa,  the XPR design must insure that both echoed characters and any
  30. left  unread  from  the previous transfer do not cause detrimental effects.
  31. While the changes to avoid these problems will not affect term programs and
  32. BBS's   using   xprzedzap.library,   the   lack   of   these   'fixes'   in
  33. xprzmodem.library make it near useless in mailers.
  34.  
  35.     Mailers  require that a session can be accomplished without reporting a
  36. failure  if  there were no files sent and/or received.  The enhancements in
  37. XPRzedzap.library address this problem.
  38.  
  39.     Mailers  also  require notification of the status of each file transfer
  40. in a batch.  This is provided by the XPR 3 function upd_status().
  41.  
  42.     Calculation  of CPS and expected transfer times are based upon the baud
  43. rate.  If the mailer does not set this to the linked rate, the calculations
  44. will  be  based  either  upon  the  Locked  rate or the prefs setting.  The
  45. C<baud> option allows passing the LINK rate for more accurate and realistic
  46. results.
  47.  
  48.     The maximum packet size can be set with a maximum/default at 8192 and a
  49. mimimum  of  64.   This  will  vary  when  sending  and will be static when
  50. receiving.   When  receiving, it should be 8192 but the maximum packet size
  51. can be set to less than if the local system has a slow HD.
  52.   When sending the maximum packet size will be baud rate dependant, and the
  53. size is calculated with the formula:
  54.                 MAX_PACKET = (BPS_RATE * 8192 / 9600).
  55. If C(baud) is passed, the link rate will be used for these allocations.
  56.  
  57.     The  IO  Buffer  for  reading/writing to/from the disk must be equal to
  58. twice   the   maximum   packet  size  (or  the  maximum  packet  size  will
  59. automatically be decreased).
  60.  
  61.     Example Protocol Setups for xprzedzap.library and Mailers:
  62.  
  63.     The defaults for xprzedzap.library are set in such as way as to require
  64. minimal changes for each protocol.
  65.  
  66.  
  67.     TN       No Text translation
  68.     OR       Overwrite Resume
  69.     B16      Buffer size 16KB 
  70.     F0       Frame size = filelength 
  71.     E30      Error count 30 
  72.     SN       Do not send full directory path  
  73.     RN       Do not use received full directory path  
  74.     AN       Disable Auto-activate mode  
  75.     DN       Do not Delete after sending  
  76.     KY       Keep partial files  
  77.     P""      Comm progrmas provides Path to use for received files  
  78.     M8192    Maximum packet size 8K 
  79.     C0       Set Link BPS Rate  
  80.     NY       Alow Send if there are no files  
  81.     QN       Disable DirectZap escape only CAN  
  82.     ZY       Enable FTN mode  
  83.  
  84.  
  85.     Zmodem      used for user uploads/downloads (GRAB, for example)
  86.                 M1024,ZN,C$(Baud)
  87.  
  88.     SZmodem     It is possible that M8192 will work if the user is using
  89.                 SZmodem or 8K-Zmodem.
  90.                 M8192,ZN,C$(Baud)
  91.  
  92.     DirectZap   uses 8K blocks, allows NoFiles transfer, escapes only ZDLE
  93.                 and ZDLEE
  94.                 QY,C$(Baud)
  95.  
  96.     ZedZip      uses 1K blocks, allows Nofiles transfer
  97.                 M1024,C$(Baud)
  98.  
  99.     ZedZap      up to 8K Blocks, allows NoFiles transfer
  100.                 C$(Baud)
  101.  
  102.     If  your  mailer  does  not  support  inbound RESUME, you must add 'ON'
  103. (OverWrite Never) to the setup string in order to override the default 'OR'
  104. (OverWrite Resume) and 'KN' (Keep Never) to override the default 'KP' (Keep
  105. Partial).
  106.  
  107.     The New Setup options: 
  108.  
  109.     Z   - FTN mode
  110.     The Z option enables FTN operation, when Y, the following is in effect:
  111.         - RxTimeOut is restored to 600ms
  112.         - transfers start with blocksize specified in M option.
  113.         - serialbuffer is cleared before sending/recving.  In FTN
  114.           mode the turnaround from sending to receiveng (and vis-versa)
  115.           is quite fast, clearing the buffer avoids reading echos of our
  116.           own characters or leftovers from the previous transfer.
  117.         - affects selection of protocol name
  118.     
  119.     C<link bps>
  120.     Buffer allocations and calculations of CPS will be based upon LINK rate
  121.     if  passed  with  C<baud> option, otherwise they will be based upon the
  122.     LOCKED rate.
  123.         
  124.  
  125.     N   - send no files mode (DirectZap,  ZedZip  and  ZedZap protocols)
  126.     It is permitted to have a session without sending or receiving files if
  127.     N  option is Y.  This is required with some protocols in FTN mode so as
  128.     not  to  generate a spurious failure after a mailer session.  This also
  129.     chnages EOF mode from sending CAN's to just sending ZFIN.
  130.         
  131.     Q   - DirectZap mode
  132.     Only ZDLE adn ZDLEE will be escaped is Q option is Y (DirectZap protocol)
  133.  
  134.  
  135. Status Display:
  136.  
  137.     XPR  2.001  support  for  dual-status windows added.  (tested, but note
  138. that  there is no publically available version of wpl.library that supports
  139. this)
  140.  
  141.     Protocol name displayed will be one of: 
  142.         Zmodem, 1K blocks standard, up to 8K, non-ftn mode
  143.         ZedZap, up to 8K Blocks based upon bps rate, ftn mode
  144.         ZedZip, 1k blocks , ftn mode
  145.         DirectZap, up to 8k blocks, minimum escaping, ftn mode
  146.  
  147.     Added  localization  for  new  options.   These  are NOT translated for
  148.     german catalog, so that catalog has been removed from distribution.
  149.  
  150.     During  batch  transfers,  Error  message  field is set to "None" when
  151.     starting to send or receive next file.
  152.  
  153. wpl concerns:
  154.     XprSetup  does  not  read  any  variables,  so you must set option C to
  155. $(baud)  so  that  all calculations are based upon the actual link rate and
  156. not the locked rate.
  157.  
  158.    XprSetup makes an XPR library ready for a transfer.  The first parameter
  159. given  is the xpr library name, and the second parameter is a string passed
  160. to  the xpr library with XProtocolSetup().  The variable $(XprSetup) is set
  161. to  the  numeric  return  of  XProtocolSetup().   A  value of 0 indicates a
  162. failure, otherwise the setup was successful.
  163.  
  164.    Return Values in $(Setup) are or'ed from the following:
  165.  
  166.         XPRS_FAILURE    0x00000000L 
  167.         XPRS_SUCCESS    0x00000001L
  168.         XPRS_NORECREQ   0x00000002L
  169.         XPRS_NOSNDREQ   0x00000004L
  170.         XPRS_HOSTMON    0x00000008L
  171.         XPRS_USERMON    0x00000010L
  172.         XPRS_HOSTNOWAIT 0x00000020L
  173.         XPRS_NOUPDATE   0x00008000L
  174.         XPRS_XPR2001    0x00010000L *
  175.         XPRS_DOUBLE     0x00020000L *
  176.  
  177.     *  Note:  private jammail versions of wl.library required both returned
  178. to  enable  dual-status  display.  This is WRONG.  Only XPRS_XPR2001 should
  179. trigger use of dual-status display.
  180.  
  181.         Normally returns:
  182.     XPRS_SUCCESS | XPRS_NORECREQ | XPRS_HOSTMON 
  183.         | XPRS_DOUBLE | XPRS_XPR2001
  184.     or
  185.     XPRS_SUCCESS | XPRS_NORECREQ | XPRS_DOUBLE | XPRS_XPR2001
  186.  
  187.  
  188.    Return values in $(RC) are as follows:
  189.       0 - All OK.
  190.       1 - XProtocolSetup returned FALSE.
  191.       2 - Library not able to be opened
  192.       3 - Out of memory.
  193.       4 - Wasn't given required modem.
  194.  
  195.     -Robert Williamson
  196.  
  197. Credits:
  198. -Chuck Forsberg for the original ZMODEM specs
  199. -Rick Huebner for the original xprzmodem.library (--> v2.10)
  200. -William M. Perkins for the 32bit CRC improvements (2.50)
  201. -Yves Konigshofer for the changes to allow ZedZap-type transfers
  202.  and a lot of advice by phone during the conversion process
  203. -Rainer Hess for addition of locale support
  204.  
  205. Debits:
  206. -Rainer  Hess  for  NOT acknowledging Yves's development.  Many features he
  207. claimed he added first appeared in Yves's sources.
  208.